{ FilerComm.text, 3-dan-83, F.Ludolph 3 € Copyright 17983, Apple Computer Inc. } 


UNIT FilerCommj 


INTERFACE 


USES {SU obj:Sys sCall 
{$U abj:PSysCall 
{4U obj rUnitStd >} UnitStd, 
{$U obj:UnitHz =) UnitHz, 


3} SysCall, 

3 

} 

—  Y 

{$U obj Storage } Storage, 
} 

3 

} 

3 


3 PSysCall, 


{$U obj Fon tMar > FontMer, 
€$U obj:QuickDraw 3} QuickDraw, 
{SU obj:WM.Events 3} Events, 
$U obj :UM. folders } Folders; 


{$SETC fcDebug = | #DbgOk } 
{$SETC fcSymbols = | #Sym0k } 


{ This unit contains the record definition used for Filer-Application 
communications. It is used in both receiving events from and sending 
events to the Filer. 


An application is started by the Filer via the OS call “Make Process’. 
The application should execute its initialization code and then 

call GetEvent. The initilialization code should first call “Open 

(to set up the Filer-Application communication channel) and then dectare 
a Sys_Terminate exception handler. I the exception handler cannot be 
declared or if initilization cannot be completed, the application should 
“TellFiler’ that *feInitFailed’ and the reason (see the section on 
unsolicited messages in the table below). See the Bouncing Balls 
‘Initialize’ procedure for an example. 


The Filer sends a FilerEvent to an application. The GetAddParams 

procedure is used to obtain the additional parameters associated with 

this event. Two parameters are passed: a filerOp that defines the 
operation to be performed, and an optional pathname, fDocName, which is 
used to open, create, and destroy the diskfiles that make up the document. 

An application uses fDocName as a prefix for disk#ile pathnames. It consists 
of a disk volume name and the initial characters of a diskfile name. 


There are currently 9 €i jlerOps, those that open a document, those that 
close or copy an open document, one that tells an application to close 
a diskfile, and one that tells the process to terminate. . 
Those that open: 
#cNone: No doe to open. The user pulled a tool rather than a doc. 
#cResume: Open the doc, or create a new doc if no diskfiles exist, and 
display contents in window. 1f the doc was suspended, restore 
its state. | 
Those that close: | 


¢cClose: Update and close doc overwriting the old version. 
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fcCopys Update doc into new diskfiles and close. ~The source doc is 
unchanged and remains open. 

$cPut: Update and close doc to new location (fDocName). Destroy the 
old version. 

#cShred: Close the doc as in fcSuspend, if possible, or just close the 
diskfiles, if possible. Filer will delete them later. 

feSuspend: Close doc, Keep edits seperate, save document, state. 


#cDtClose: Close the diskfile Cnot document) using the refnum provided 
else app will be terminated. (User is removing a diskette.) 


Terminate: 


4cTerminate: Ponninaty the process and suspend any open docs (actually 
there shouldn’t be ary open when this is received). 


An #cResume/fcNone is sent when: 


1) the user pul a _ document onto the Pues (¥cResume) | or 


The window to be used to disply the document is provided by the Filer 

via eventRecord.who in the open event. The application should never dispose 
of this window, i.e. call WM.DisposeFolder. NOTE! A reply is no longer 
expected. The Filer assumes that the document was opened without error... 

lf errors do occur, the application should send an unsolicited docClose to the 
Filer (see below. | 


A close type of filerdp is sent if a user puts away a document or its — 

diskette is unmounted. If a document is being put away any edits to the 
document should be made permanent, however, if the diskette is being unmounted, 
the document’s current state should be saved and the edits maintained seperately. 


For ¢irst release applications may put away edits or save state as 
they chose. If .time permits put away and save state should be 
implemented as described above, 


A terminate is sent when the app] ication is to ienvinate, usually because 
the diskette that holds the application is being unmounted. After calling 
“ImDying’, if the application still has some open documents, they should be 
suspended by the application before it terminates. 


A NOTE ON “ImDy ing’ + This message should always be sent to the Filer as 
“the first thing done by the appiication’s terminate exception handler, 
whether in response to a Filer event or unsolicited. If an application 
terminates before making this call, it is likely the case that all other 
processes, ‘nc ludtng the Filer, are suspended and so the system will hang. 


When an application has completed processing the Filer initiated event, 

it sends a response back to the Filer via the “TellFiler’ procedure. 

«Some events do not require a response.) Appropriate responses for each event 
are listed below. Note that several operations can be aborted by the user. 


In general, the application is responsible for informing the user of any | 
difficulties via the alert box. Be sure that the window is the active window . 
before using the alert box. ° 
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The “TellFiler’ procedure is also used te send pre-defined replies and unsolicited 
messages to the Filer. The only unsolicited messages currently defined are 
f#cDocClosd Be TEST PET ESy an abnormal TACOS OR ORUD Ne: PERSE MN Ine tte hi zet Tons 


An application is also responsible for maintaining several menu items and 
informing the Filer via DoFil ingCmd when the user invokes them. The menu 
layout is defined in Tesler’s “Menu Terminology’ memo of May 30, 1982. The 
items of interest are all in the first menu: | 


Menu item -:DoFilingCmd parameter 


Close Everything on Desk cmdCloseAl} 
Ciose "window title” : cmdClose 
Save & Put Back ( see below ) 


When the user invokes “Save and Put Back’ the application should attempt to 
close the document as if it had received an #cClose Filer event. 14 the 

close is sucessful, “TellFiler’ docClosd with reason of putBack. If the close 
mat hot Bucerestdts ter) the user why via alerts ~- DON’T TELL THE FILER. 


The CopyDoc procedure is provided for application use. It copies all document 
diskfiles from the source prefix to the destination prefix. The number of an 
unbound LDSN must also be provided. The CopyDoc routine temporarily opens a large, 
memory-resident data segment for data transfer. The data segment is unbound and 
destroyed before CopyDoc returns. | 


AS an alternative, the application can supply an bound data segment by negating 
the LDSN parameter. <NOTE: until additional O/S interfaces are available at 5.2, 
the application must also set useDsAdrs to the beginning address of the bound 
data segment and useDsMemSize to the data seg’s length.) 


) 
CONST 
{ Errors ~ range is 4025 thru 4049 > 


All OK | } 
User type “apple .” | } 
Event type must be docOpen/Close/Copy/Terminate} 
FReason does not match FReply > 
Cannot read from the source document } 
Cannot write to the destination document 3 
File opened privately or being written to } 
Insufficient space for 10 buffer 3 

} 

} 


feeNoErrors = ; Q; 
f#ceAborted = — «6 4033; 
fceBadEventType = 4025; 
fceBadReason = #4026; 
feeCantRead = = 4027; 
feeCantWrite = 4028; 
‘fcelnUse = | 4029; 
#ceNoMemory = 4030; 
fceOutOf0i skSpace = 40313 
#ceBadLDSN = 0325 


Insufficient space on distination volume 


OS error attempting te use the LDSN provided} 


{ filing menu commands - for filing menu-items in app menus } 


emdClose 
emdClosAll 


1001; 


TYPE 


Pane 3 


Filingtmd = 


FilerOp = (fcClose, 


FReply = 


FReason 


Filerext 


FCopyOp. 


_ €cPut, 


LONGINT ; 


f#cCopy, 
4cD4Close, 
#cNone, 


#cResume, 
¢cShred, 
fcSuspend, 
fcTerminate); 


(déClosed, 
dfNotClosed, 
docClosd, 


docNotClosed, 


docXfered, 


docNotXfered, 


InitFailed); 


Cal lOK, - 
badData, 
cantRead, 
cantWrite, 
dirtyDoc, 
internalError 
newerDoc, 
noDiskSpace, 
noMoreDocs, 
docPutBack, 
aUserAbort)3 


theFirOp: Fi 


thePrefix: Pathname; 
theDF: INTEGER: 


END; 


C#eDoeCopy, 
fcDocMove , 
Feber kackup>3 


CS eee ie 


Update and close doc using same diskfile names 
Update doc into new diskfiles, source unchanged 
Close the diskFile for the refnum provided 

Neo doc to open, i.e. user executed program. 
Update and close doc to new location ¢fDocName) 
Open doc and display content in window 

Close the doc and delete the diskfiles 

Close doc, Keep edits seperate, save state 
Terminate process, suspend any open docs 


Reply to #cDfClose 

—Reply,to feDfClose 

Reply to fcClose, fcSuspend, fcShred 
Reply to fcClose, feSuspend, fcShred 
Reply to fcCopy, fcPut 

Reply to.fcCopy, fcPut 

Unsolicited, app could not initialize 
fcTerminate reply is “ImDying’ call 
fcNone does not require a reply 


BP Pt yt ke a te 


FilerOp completed without error or problem 4 
Unable to display the document | 2 
Unable to read in the document } 
Unable to write out document, disk problems} 
The document was edited an may be inconsistent} 
| Unexpected program error at any time 2 
Doc created by newer version of app ; 
Insufficient disk space to complete FilerOp) 
Insufficient memory for data segments, etc.? 
App can’t handie any more documents } 
FilerOp completed, but no more docs please 
App processed menu ‘Put Back? 

User aborted filerOp 


olakatakekeketadelakekakte 
Ray Saya Fay 


{ Returned by “GetAddParms’ 3} 
lerOp; € The requested operation } 
< Diskfile name prefix } 
{ Diskfile refnumtfcD4Close) 3 


{ Set disktile DTC to now, DTM to 0 er a 
{ Duplicate DTC, DTM values } 
= Duplicate OTC, DTM. Set DTB on source diskfile} 


 catanbaeaebbaeieaimetomiteeiaeiantoamiaaeeiammmmmenmmmmmmmmmmmamammammnemmammmest 


{* 
(* 


{# 
Le 


{% 


#3 


The following TYPEs are exported only for use by other Filer UNITs. %} 
They can and should be ignored by all other users. . | #} 


HFilerExt = 
pFilerExt = 


“pFilerExt; 


“FilerExt; 


¥} 
{ EventRecord.userData as a handle? 


RF 
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ReplyPtr = “Reply; 
Reply = RECORD { Redefines EventRecord.userData 3} 
| theReply: FReply; : 
theReason: FReason; 
END; 
GEHEEE HERE EE THERE HOU EI HEHEHU IU nEIE EEE EEE EERE HEeEREREEE) 


PROCEDURE CopyDoc (VAR error: INTEGER; fromPrefix, toPrefix: Pathname; useLdsn: INTEGER § 
theOp: FCopyOp; VAR docSize: LONGINT); 


{ .This precedure copies all diskfiles in the “fromPrefix’ document to the 
“toPrefix’ document. The document ig tranterred via the dataseg bound to useLDSN. 
If useLDSN is positive, this procdure will temporarily bind its own data seg 
for the duration of the operation. A negative useLDSN indicates that the caller 
has already bound a dataseg to useLdsn Cit should be of copyDsSize if peer 
TheOp determines how a diskfile’s DTM, DTC, and DTB fields are to be set. 
Applications should always pass ‘“fcDocCopy’. DocSize returns the number of HGtES, 
including file system overhead, occupied by the document’s diskfiles. 


Errord: fceNoErrors, fceAborted, fceCantRead, fceCantWrite, fceOutO4DiskSpace, 


fteNoMemory 3} 


PROCEDURE DoFilingCmd Cwhich€md: FilingCmd); 


{ This procedure i's used by an app! ication when a filing menu i tem is selected. } 


PROCEDURE Ge tAddParms (VAR error: INTEGER: theEvent: EventRecord; 
VAR theFilerExt: FilerExt); 


{ This procedure is used to access the additional paramters sent with Filer- 
related events: docOpen, docClose, docCopy, and docTerminate. “userData’ 
is the EventRecord.userData field ¢rom the received event. If the event 
type is not one of those four, the badEventType error is returned. 


errors: fceNoErrors, fceBadEventType } 
PROCEDURE TeliFiler «VAR error: INTEGER; what: FReply; why: FReason; 
myFolder: WindowPir): =e 
{ This procedure is used by an application to send a message to the Filer. 
Usually is it used to reply to an event sent by the Filer Ca reply is nearly 
always required), but it is also used to send an unsolicited nereeoes such 
as abnormal termination, to the Filer. 
*MyFolder’ is the primary window used to display the document, i.e. the 
one passed in on the docQpen event. It can be NIL i€ there isn’t an 


open document. 


‘what’ and ‘why’ constitute the message that your are sending the Filer: 
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IN RESPONSE TO VALID “WHAT’S VALID “WHYS 


fcResume, feNone 


fcClose docClosd all OK 


docNotClosed cantWrites: 
cantRead: 
dirtyDoc: | 
noDiskSpace: 
noMemory: 
internalError: 
alserAborts 
docClosd 


“fceShred aj 10K 


feSuspend docClosd allOK 
cantWrite: 
cantRead: 
noDiskSpace: 
noMemor y: 
internalError: 
aUserAbort: 


docNotCieced 


fcCopy, fcPut docXfered alloK 
canthri tes 
cantRead: 
dirtyDoc: 
noDiskSpace: 
internalError: 
aUserAbort: 


docNotXfered 


feTerminate “response” is a 


allo 
internalError: 


dfClosed 
d#NotClosed 


4cD4Close 


no response required if doc opened ok. 


disk 1/0 problems 

unable to read doc diskfiles 
edited doc may be inconsistent 
can’t write new diskfiles 
machine is too small 
application error, last resort 
user abort 


disk 1/0 problems 
unable to read doc disktiles 
can’t write new diskfi les 
machine is too small : 
application error, last resort 
user abort | 


disk 1/0 problems 


unable to read doc diskfiles 
edited doc may be inconsistent 
can’t write out new doc 
application error, last resort 
user abort — 


tall to “ImDying’ 


for any reason 


SS cams cot ee Sain aA SESS OLE TG DS ae OREN NN AER pp a NY SEY : ae ~4 = ORS SSE EID ANY ENS SA HRSD ET AI ONSET ER LED AID CARRE GORD CO AA AAS TRATED SAE CAMELS COPUNG: SEY SED DEY SD CORA SAMMI ECO? OR a GE CORA RA MLR RA 


UNSOLICITED MSGS VALID “WHAT‘’S VALID ’WHY’S 
badData: 
newerDoc : 
noDiskSpace: 
noMemory: 
noMoreDocs: 
internalError: 


can’t display doc docClosd 


user abort fcResume docClosed alserAbort: 


doc “PutBack’ . | docClosd 


docPutBack: 


initFailed noDiskSpace: 


noMemory: 


prog initizat‘n 
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doc damaged during operation | 
doc version newer than app ver. 
can’t open data segs, etc. 
can’t open data segs, etc. 


can’t open another doc. (fcNone) 


application error, last resort. 
user pushed “command .° 
doc closed as user requested. 


can’t open data segs, etc. 
can’t open data seas, etc. 


internalError: application error, last resort. 
aUserAbort: user. abort 
DO NOT NEED TO CALL “ImDying’ after this. 


errors: fceNoErrors, fceBadEventType, fceBadReason } 


oe 


{HEERERHSR ERE EASES REA RE RIESE ERIE HERE AER E ERNE LE AERA RTI HERAT IH ED 
{% | #} 
€% The following procedures are for use by the Filer only. #3 
{8 #3 
HLH EKESKKSLELAKE SE SEALE SEER KKK KEKE HE RKKLEAK EREKARR LE RHE KA SSR LKRKKR AS SHREK R KKH EKER} 


PROCEDURE CopyDiskfile (VAR err: INTEGER; source, destination: Pathname; 
bufra drs ; bu fr S i et LONGINT F ¢ heOp s FCopyOp : 
VAR osErr: INTEGER): 


_ IMPLEMENTATION 


{$1 FC FeSymbols } 
{$D+ } 

{$ELSEC } 
{$ENDC. 3} 


{$IFC FeDebug ?} 
{$R+ 3 

€$ELSEC } 

{SR- ) 

{$ENDC )} 


{$1 1:FCimpl.text} 
END. 
€ 
Change Log: 
53-Oct-82 AZ Release 
20-Oct-82 Added FReason “docPutBack’, updated doc for streamlined protocol 
28-Oct-82 Deleted FReply ‘diskFreed’, ‘“diskNotFreed’, FilerOp “freeDisk’, 
and FilerExt ‘bytesReqd’. 
Added error fceAborted and poe neers FCopy param. 
i-Nov-82 AZ Release 
2-Nov~82 AZ ReRelease 
5-Nov-82 Added “alserAbort’ reason to several replies. 
9-Nov-82 AQ ReRelease | _ | 
3-Jan-83 Removed “cmdPutBack’, ‘’docOpened’, “docNotOpened’ - support for old protocols. 


3-Jan-83 A4 pre-release 
S-Jan-83 Added ‘newerDoc’ to #Reason 
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